Fox's Git Mirrors - /page/blob.mu

Node / rns-mirrors / Reticulum-Go.git / files / docs / en / configuration.md

Displaying Rendered • View raw • Download

Reticulum-Go reads the same INI-style configuration shape as Python Reticulum. The canonical parser lives in T383838pkg/reticulumconfig. The daemon imports it through T383838internal/config.

Default config path:

T282828

~/.reticulum-go/config

Override with T383838--config on the daemon command line.

T282828

~/.reticulum-go/

config

storage/

identities/

cache/

announces/

resources/

ratchets/

blackhole

destination_table

known_destinations/

transport_identity

dos_protect.mpack

Python uses T383838~/.reticulum or T383838/etc/reticulum by default. Reticulum-Go uses a separate directory so both stacks can run on one host.

T383838storage/ratchets/ holds known-peer public keys named by destination hash (Python T383838{ratchet, received} msgpack) and destination-private signed lists at the path T383838EnableRatchets was given. Pageserver names that file by destination hash, same as Python LXMF. T383838EnableRatchetsInMemory and T383838in_memory_storage keep ratchet material in RAM.

┌──────────────────┬────────────────────────────────────────────────────────┐

│ Aspect │ Behavior │

├──────────────────┼────────────────────────────────────────────────────────┤

│ Sections │ T383838[reticulum], T383838[logging], T383838[[Interface Name]] │

│ Interface blocks │ Double-bracket headers at nesting depth 2 │

│ Comments │ T383838# or T383838; (including end-of-line after a space) │

│ Booleans │ yes, no, true, false, on, off, 1, 0 (case insensitive) │

│ Unknown keys │ Ignored (allows boot with extra or damaged lines) │

│ UTF-8 BOM │ Stripped on read │

│ Missing file │ Default config is created │

└──────────────────┴────────────────────────────────────────────────────────┘

┌────────────────────────────────┬──────────────────────────────┬──────────────────────────────────┐

│ Key │ Default │ Description │

├────────────────────────────────┼──────────────────────────────┼──────────────────────────────────┤

│ enable_transport │ yes │ Enable transport routing and pa… │

│ share_instance │ yes │ Use shared instance multiplexing │

│ sharedinstanceport │ 37428 │ TCP port for shared instance │

│ instancecontrolport │ 37429 │ Control port when this process … │

│ sharedinstancetype │ unix on Linux, tcp elsewhere │ tcp or unix (unset uses platfor… │

│ instance_name │ (empty) │ Unix socket name when type is u… │

│ rpc_key │ (empty) │ Hex key for shared-instance RPC… │

│ enable_sandbox │ yes │ Apply OS sandbox after startup … │

│ enable_seccomp │ yes │ Linux seccomp-bpf denylist afte… │

│ sandbox_strict │ no │ Exit if Landlock, seccomp, Open… │

│ sandbox_profile │ full │ T383838full keeps T383838/bin for pipe and pa… │

│ sandboxextrapaths │ (empty) │ Comma-separated extra filesyste… │

│ sandboxexecrlimits │ no │ Linux only. Apply NPROC=32 and … │

│ enablecontrolapi │ no │ Start localhost control API │

│ controlapihost │ 127.0.0.1 │ Control API bind address │

│ controlapiport │ 37430 │ Control API port │

│ controlapisocket │ (empty) │ Optional Unix socket path in ad… │

│ backbone_io │ auto │ Backbone poller: auto, epoll, k… │

│ inmemorypath_table │ no │ Keep path table in RAM only │

│ inmemoryknown_destinations │ no │ Keep known destinations in RAM … │

│ inmemorystorage │ no │ Fully ephemeral mode: no disk f… │

│ identity_backend │ file │ Identity at-rest store: file, s… │

│ softmemorylimit │ (none) │ Soft heap budget (K/M/G or byte… │

│ dos_protection │ auto │ Go-only local IDS/IPS gates. Va… │

│ maxinmemory_paths │ 100000 │ Soft cap on the live path table… │

│ maxinmemoryknowndestinations │ 100000 │ Soft cap on known destinations … │

│ maxinmemoryresourcebytes │ 256M │ Split-resource staging budget w… │

│ maxpackethashlist │ auto │ Packet hash loop-filter size. Z… │

│ maxpackethandlers │ 512 │ HandlePacket worker count and q… │

│ node_profile │ default │ Go-only overlay: T383838default, T383838core_… │

│ discover_interfaces │ no │ Start rnstransport interface di… │

│ watch_interfaces │ no │ Poll NIC up/down and rescan Aut… │

│ statictransportidentity │ no │ Keep persisted transport identi… │

│ localhopsdelta │ no │ Mangling applied on local-origi… │

│ respondtoprobes / allow_probes │ no │ Register rnstransport.probe wit… │

│ enableremotemanagement │ no │ Register T383838rnstransport.remote.ma… │

│ remotemanagementallowed │ (empty) │ Comma-separated identity hashes… │

│ network_identity │ (empty) │ Path to network identity for di… │

│ paniconinterface_error │ no │ Panic on fatal interface errors │

└────────────────────────────────┴──────────────────────────────┴──────────────────────────────────┘

T383838node_profile fills unset knobs. Keys present in the file are never overwritten.

┌─────────────┬────────────────────────────────────────────────────────────────────────────────────┐

│ Profile │ Effect when unset │

├─────────────┼────────────────────────────────────────────────────────────────────────────────────┤

│ default │ No overlay │

│ core_router │ T383838dos_protection=prevent, T383838backbone_io=auto, T383838watch_interfaces=yes, T383838max_packet_handle… │

│ embedded │ T383838max_packet_handlers=32, T383838max_in_memory_paths=4096, smaller known-dest and hashlist… │

└─────────────┴────────────────────────────────────────────────────────────────────────────────────┘

Local overload gates in T383838pkg/protect. They keep this node alive under floods and resource storms. They do not ban peers mesh-wide and do not replace IFAC, link crypto, or Sybil-resistant admission policy.

┌──────────────────────────────┬───────────────────────────────────────────────────────────────────┐

│ Mode │ Behavior │

├──────────────────────────────┼───────────────────────────────────────────────────────────────────┤

│ off │ Disabled │

│ detect (alias ids) │ Trip, count, and rate-limited stdout warnings. Traffic still flo… │

│ prevent (aliases block, ips) │ Same as detect, and shed or block on trip │

│ auto (alias smart, default) │ Learn quietly, then arm prevent. Relearn on interface fingerprin… │

└──────────────────────────────┴───────────────────────────────────────────────────────────────────┘

Example:

T282828

[reticulum]

dos_protection = auto

Learning state is written as msgpack to T383838{config_dir}/storage/dos_protect.mpack (atomic replace). Restarts restore armed baselines when the interface fingerprint still matches.

Optional limits (zero or unset keeps built-in defaults):

┌─────────────────┬────────────────────────────────────────────┐

│ Key │ Purpose │

├─────────────────┼────────────────────────────────────────────┤

│ dosmaxpps │ Absolute per-iface packet rate ceiling │

│ dosmaxbps │ Absolute per-iface byte rate ceiling │

│ dosfloorpps │ Minimum adaptive trip line (pps) │

│ dosfloorbps │ Minimum adaptive trip line (bps) │

│ dosmaxconns │ Concurrent stream accepts per iface │

│ dosmaxresources │ Concurrent incoming resources process-wide │

│ dosmaxcrypto │ Concurrent crypto verify jobs │

│ dosmaxhandshake │ Concurrent link handshake jobs │

└─────────────────┴────────────────────────────────────────────┘

Ingress uses interface bitrate when available to scale adaptive floors. Link and proof traffic may stay admitted slightly above the trip line before announce-class traffic is shed.

Operator visibility: T383838reticulum-go status -json and shared-instance T383838interface_stats include a T383838protect object (mode, phase, trip lines, cool-down). Control API T383838GET /v1/status includes the same T383838protect block.

Surfaces gated when mode is not off:

┌────────────────────────────┬─────────────────────────────────────────────────────────────────────┐

│ Gate │ Typical attack class │

├────────────────────────────┼─────────────────────────────────────────────────────────────────────┤

│ Per-iface packet pps / bps │ Packet floods (adaptive EWMA baseline, once-per-second peak sample… │

│ Handler overflow │ Packet handler overload │

│ Stream accepts │ TCP / QUIC / VSOCK / I2P / Local connection storms │

│ Incoming resources │ Resource / transfer pile-up │

│ Crypto jobs │ Decrypt / verify / HMAC storms │

│ Handshakes │ Link setup / proof floods │

│ Memory shed │ Soft heap pressure (pairs with softmemorylimit) │

│ Iface cool-down │ Temporary hard reject after a burst of trips on one iface │

└────────────────────────────┴─────────────────────────────────────────────────────────────────────┘

Stdout trip lines look like:

T282828

WARNING: dos_protection prevent trip reason=pps iface=udp0

WARNING: dos_protection auto/learning trip reason=pps iface=udp0

WARNING: dos_protection auto promote reason=stable phase=armed

WARNING: dos_protection auto relearn reason=network phase=learning

Health kinds T383838dos_* increment on trips. See Security and Development and testing.

┌─────────────────────────┬────────────────────────────────────┐

│ Key │ Notes │

├─────────────────────────┼────────────────────────────────────┤

│ publish_blackhole │ Blackhole auto-publish not started │

│ blackhole_sources │ Ignored │

│ blackholeupdateinterval │ Ignored │

└─────────────────────────┴────────────────────────────────────┘

localhopsdelta applies a random hop field (2-7) on locally originated hop-0 packets when not connected to a shared instance.

┌─────────────┬────────────────────────────────────────────────────────────────────────────────────┐

│ Key │ Supported │

├─────────────┼────────────────────────────────────────────────────────────────────────────────────┤

│ loglevel │ Yes (0 through 7) │

│ destination │ Yes (stderr, file, both, syslog, journald, and combinations such as T383838syslog+stderr) │

│ logfile │ Yes (default T383838{config_dir}/logfile/reticulum.log) │

│ format │ Yes (text or json) │

└─────────────┴────────────────────────────────────────────────────────────────────────────────────┘

Each block defines one interface. Common keys:

┌────────────────────────────────┬───────────────────────────────────────────────────────────┬─────┐

│ Key │ Applies to │ De… │

├────────────────────────────────┼───────────────────────────────────────────────────────────┼─────┤

│ type │ All │ In… │

│ enabled / interface_enabled │ All │ En… │

│ mode / interface_mode │ All │ fu… │

│ recursive_prs │ All │ Di… │

│ announcesfrominternal │ All │ Re… │

│ address / listen_ip │ UDP, TCP/QUIC/WebTransport/HTTPS server, DNSRendezvous │ Bi… │

│ port / listen_port │ UDP, TCP/QUIC/WebTransport/HTTPS/VSOCK server, DNSRendez… │ Bi… │

│ targethost / targetport │ TCP, QUIC, WebTransport, HTTPS client │ Re… │

│ target_address │ UDP │ Re… │

│ interface │ Auto │ OS… │

│ prefer_ipv6 │ TCP, Auto │ Pr… │

│ maxreconnecttries │ TCP, UDP, backbone, QUIC, WebTransport, HTTPS, VSOCK │ T383838-1… │

│ bitrate │ All │ De… │

│ mtu │ All │ In… │

│ discovery_port │ Auto │ Mu… │

│ data_port │ Auto │ Da… │

│ discovery_scope │ Auto │ Mu… │

│ group_id │ Auto │ Gr… │

│ multicastaddresstype │ Auto │ Mu… │

│ announce_cap │ All │ Ca… │

│ T383838announce_rate_* │ All │ An… │

│ ingress_control / T383838ic_* │ All │ In… │

│ network_name │ IFAC │ IF… │

│ passphrase │ IFAC │ IF… │

│ T383838ifac_* │ IFAC │ Ad… │

│ sam_address │ I2P │ SA… │

│ peers │ I2P │ Ou… │

│ connectable │ I2P │ SA… │

│ i2p_tunneled │ TCP client, backbone client │ Tu… │

│ command │ Pipe │ Ex… │

│ respawndelay / respawninterval │ Pipe │ Se… │

│ sharedinstancetype │ Local │ tc… │

│ instance_name │ Local │ Un… │

│ certfile / keyfile │ QUIC, WebTransport, HTTPS │ Op… │

│ peer_key │ QUIC, WebTransport, HTTPS │ Le… │

│ sni │ QUIC, WebTransport, HTTPS client │ TL… │

│ path │ WebTransport, HTTPS │ UR… │

│ transport_mode │ WebTransport │ da… │

│ domain │ DNSRendezvous │ DN… │

│ resolve_interval │ DNSRendezvous │ Se… │

│ context_id / cid │ VSOCK client │ Pe… │

│ longpollsec │ HTTPS │ Lo… │

│ outgoing / selected_outgoing │ All │ Tr… │

└────────────────────────────────┴───────────────────────────────────────────────────────────┴─────┘

Unknown type values load Go-native plugins from T383838{config_dir}/interfaces/ (JSON manifest or executable pipe driver), or from T383838interfaces.RegisterExternalFactory.

┌─────────────────────────────┬─────────────────────────────────────────────────────┐

│ type value │ Implementation │

├─────────────────────────────┼─────────────────────────────────────────────────────┤

│ UDPInterface │ T383838pkg/interfaces/udp.go │

│ TCPClientInterface │ T383838pkg/interfaces/tcp.go │

│ TCPServerInterface │ T383838pkg/interfaces/tcp.go │

│ AutoInterface │ T383838pkg/interfaces/auto.go │

│ I2PInterface │ T383838pkg/interfaces/i2p.go │

│ BackboneInterface │ T383838pkg/interfaces/backbone.go │

│ BackboneClientInterface │ T383838pkg/interfaces/backbone_client.go │

│ PipeInterface │ T383838pkg/interfaces/pipe.go │

│ LocalInterface │ T383838pkg/interfaces/local.go (client to shared instance) │

│ LocalServerInterface │ T383838pkg/interfaces/local.go (explicit server block) │

│ WebSocketInterface │ Go-only, native or WASM │

│ QUICClientInterface │ Go-only, native (T383838quic-go) │

│ QUICServerInterface │ Go-only, native (T383838quic-go) │

│ WebTransportClientInterface │ Go-only, HTTP/3 WebTransport │

│ WebTransportServerInterface │ Go-only, HTTP/3 WebTransport │

│ DNSRendezvousInterface │ Go-only, DNS TXT to UDP peer │

│ VSOCKClientInterface │ Go-only Linux, AF_VSOCK HDLC │

│ VSOCKServerInterface │ Go-only Linux, AF_VSOCK HDLC │

│ HTTPSClientInterface │ Go-only, TLS long-poll │

│ HTTPSServerInterface │ Go-only, TLS long-poll │

└─────────────────────────────┴─────────────────────────────────────────────────────┘

T282828

[[Gateway]]

type = TCPClientInterface

enabled = yes

target_host = mesh.example.com

target_port = 7825

network_name = MyMesh

passphrase = long-random-secret

ifac_size = 16

max_reconnect_tries = 0

T383838max_reconnect_tries = 0 means no reconnect attempts after disconnect. Omit the key or set T383838-1 for unlimited retries.

T282828

[[QUIC Hub]]

type = QUICServerInterface

enabled = yes

listen_ip = 0.0.0.0

listen_port = 4242

[[QUIC Uplink]]

type = QUICClientInterface

enabled = yes

target_host = hub.example.com

target_port = 4242

peer_key = aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899

max_reconnect_tries = -1

QUIC is Go-only. TLS uses ephemeral self-signed certificates by default. Set peerkey to the remote leaf SPKI SHA-256 (hex) to pin the peer. Optional certfile / key_file and sni are supported. Not available on WASM.

T282828

[reticulum]

watch_interfaces = yes

[[WiFi Mesh]]

type = AutoInterface

enabled = yes

interface = wlan0

discovery_port = 35615

data_port = 35616

watch_interfaces rescans NICs when link state changes and helps AutoInterface follow Wi-Fi roam events.

T282828

[[Radio Bridge]]

type = PipeInterface

enabled = yes

command = /opt/mesh/radio-bridge --stdio

respawn_delay = 5

Reticulum writes HDLC-framed packets to the subprocess stdin and reads frames from stdout. When the subprocess exits, the interface respawns after respawn_delay seconds.

On Linux, unset sharedinstancetype uses abstract Unix sockets (T383838@rns/<instance_name>/rpc), matching stock Python rnsd. Go utilities try that default first, then fall back to TCP when the type is unset.

T282828

make build

./bin/reticulum-go status -config ~/.reticulum -json

Optional shared auth (recommended when mixing stacks):

T282828

[reticulum]

share_instance = yes

instance_name = default

shared_instance_type = unix

rpc_key = <64 hex characters>

Use T383838shared_instance_type = tcp with instancecontrolport when you want TCP on every OS. Use T383838-config ~/.reticulum for Python rnsd and T383838-config ~/.reticulum-go for a Go shared instance. Full utility docs are in CLI utilities.

When T383838share_instance = no, attach to another process that owns the shared instance:

T282828

[reticulum]

share_instance = no

[[Local]]

type = LocalInterface

enabled = yes

port = 37428

shared_instance_type = tcp

On Unix the daemon reloads interface blocks on T383838SIGHUP via T383838node.ReloadInterfaces. Reload compares normalized config for each interface including MTU, bitrate, prefer_ipv6, announce-rate, ingress/egress control, mode, and outgoing. See Interfaces.

T282828

import "quad4/reticulum-go/pkg/reticulumconfig"

cfg, err := reticulumconfig.LoadConfig("/path/to/config")

Defaults without a file:

T282828

cfg := reticulumconfig.DefaultConfig()

Save:

T282828

err := reticulumconfig.SaveConfig(cfg)

Identity files use a 64-byte software layout (X25519 private plus Ed25519 seed). Reticulum-Go stores identity blobs under T383838storage/identities/ keyed by hash. Python may use per-name files. Both layouts are supported for loading.

Optional hardware-bound descriptors (RHB1, 72 bytes) are documented in Identity and destinations.

• Interfaces for per-type behavior and reconnect policy

• Architecture for shared instance and persistence

• CLI utilities for rgostatus / rgoid / rgoprobe and RPC setup

• COMPATIBILITY.md for full Python key comparison tables